Padroneggiare la validazione dei moduli con `experimental_useFormStatus` di React

I moduli sono la base dell'interazione web. Dalla semplice iscrizione alla newsletter a una complessa applicazione finanziaria multi-step, sono il canale principale attraverso il quale gli utenti comunicano con le nostre applicazioni. Tuttavia, per anni, la gestione dello stato dei moduli in React è stata fonte di complessità, boilerplate e affaticamento da dipendenze. Abbiamo destreggiato componenti controllati, combattuto con librerie di gestione dello stato e scritto innumerevoli gestori `onChange`, tutto alla ricerca di un'esperienza utente fluida e intuitiva.

Il team di React ha ripensato questo aspetto fondamentale dello sviluppo web, portando all'introduzione di un nuovo e potente paradigma incentrato sulle Azioni del server React. Questo nuovo modello, costruito sui principi del miglioramento progressivo, mira a semplificare la gestione dei moduli spostando la logica più vicino a dove appartiene, spesso, il server. Al centro di questa rivoluzione lato client ci sono due nuovi hook sperimentali: `useFormState` e la star della nostra discussione di oggi, `experimental_useFormStatus`.

Questa guida completa ti accompagnerà in un'immersione profonda nell'hook `experimental_useFormStatus`. Non ci limiteremo a esaminare la sua sintassi; esploreremo il modello mentale che abilita: Logica di validazione basata sullo stato. Imparerai come questo hook disaccoppia l'interfaccia utente dallo stato del modulo, semplifica la gestione degli stati in sospeso e lavora in concerto con le Azioni del server per creare moduli robusti, accessibili e altamente performanti che funzionano anche prima che il JavaScript venga caricato. Preparati a ripensare tutto ciò che pensavi di sapere sulla creazione di moduli in React.

Un cambio di paradigma: l'evoluzione dei moduli React

Per apprezzare appieno l'innovazione che `useFormStatus` porta, dobbiamo prima capire il percorso della gestione dei moduli nell'ecosistema React. Questo contesto evidenzia i problemi che questo nuovo approccio risolve elegantemente.

La vecchia guardia: componenti controllati e librerie di terze parti

Per anni, l'approccio standard ai moduli in React è stato il modello dei componenti controllati. Questo implica:

• Utilizzare una variabile di stato React (ad esempio, da `useState`) per contenere il valore di ogni input del modulo.
• Scrivere un gestore `onChange` per aggiornare lo stato ad ogni pressione di tasto.
• Passare la variabile di stato di nuovo alla prop `value` dell'input.

Sebbene ciò dia a React il pieno controllo sullo stato del modulo, introduce una quantità significativa di boilerplate. Per un modulo con dieci campi, potresti aver bisogno di dieci variabili di stato e dieci funzioni di gestione. La gestione della convalida, degli stati di errore e dello stato di invio aggiunge ancora più complessità, spesso portando gli sviluppatori a creare intricati hook personalizzati o a cercare librerie complete di terze parti.

Librerie come Formik e React Hook Form sono diventate importanti astraendo questa complessità. Forniscono soluzioni brillanti per la gestione dello stato, la convalida e l'ottimizzazione delle prestazioni. Tuttavia, rappresentano un'altra dipendenza da gestire e spesso operano interamente sul lato client, il che può portare alla duplicazione della logica di convalida tra frontend e backend.

La nuova era: miglioramento progressivo e azioni del server

Le Azioni del server React introducono un cambio di paradigma. L'idea principale è quella di costruire sulle fondamenta della piattaforma web: l'elemento HTML standard `

`. Un modulo con un'azione del server funziona come un classico invio di moduli HTML: può funzionare perfettamente anche se JavaScript fallisce o è disabilitato. Questa è l'essenza del miglioramento progressivo.

Quando JavaScript viene caricato, React dirotta il processo di invio del modulo, impedendo un ricaricamento completo della pagina ed eseguendo l'azione del server in modo asincrono. Questo ci offre il meglio di entrambi i mondi: la resilienza delle applicazioni renderizzate lato server e la ricca esperienza interattiva di un'applicazione a pagina singola (SPA).

Questo modello sposta la fonte di verità per la logica di business e la convalida di nuovo sul server (o in un ambiente simile al server). Il codice lato client diventa più semplice, principalmente interessato a renderizzare l'interfaccia utente in base allo *stato* di quella comunicazione del server. È proprio qui che entra in gioco `useFormStatus`.

Sotto il cofano: cos'è `experimental_useFormStatus`?

L'hook `experimental_useFormStatus` è uno strumento lato client progettato per fornire informazioni sull'ultimo invio di un elemento `` padre. È un hook di sola lettura che dice a un componente tutto ciò che deve sapere sullo stato di invio del modulo senza bisogno di props passate.

La funzionalità principale

Immagina un pulsante di invio all'interno di un grande modulo. Come fa questo pulsante a sapere quando il modulo viene inviato? Tradizionalmente, dovresti passare una variabile di stato come `isSubmitting` attraverso più livelli di componenti (prop drilling). Con `useFormStatus`, il componente del pulsante può scoprire queste informazioni da solo.

L'hook deve essere chiamato da un componente che viene renderizzato all'interno di un elemento ``. Fornisce quindi informazioni sullo stato del ciclo di vita di quel modulo specifico.

Anatomia dell'hook `useFormStatus`

Quando chiami `const status = useFormStatus()`, ottieni un oggetto con le seguenti proprietà chiave:

• `pending` (booleano): Questa è la proprietà più frequentemente utilizzata. È `true` se il modulo padre è attualmente in fase di invio e `false` altrimenti. È perfetto per disabilitare i pulsanti, mostrare spinner di caricamento o stilizzare stati in sospeso.
• `data` (FormData): Un oggetto che implementa l'interfaccia `FormData`. Contiene i dati che sono stati inviati con il modulo. Questo è incredibilmente utile per implementare aggiornamenti UI ottimistici, ad esempio, mostrare il commento di un utente in un elenco immediatamente dopo che lo ha inviato, anche prima che il server ne abbia confermato la creazione.
• `method` (stringa): Il metodo HTTP ('get' o 'post') utilizzato per l'invio del modulo.
• `action` (funzione): Un riferimento alla funzione di azione del server che è stata invocata durante l'invio.

La regola d'oro: un figlio del `<form>`

Una regola fondamentale da ricordare è che un componente che utilizza `useFormStatus` deve essere renderizzato come figlio dell'elemento `<form>` che sta tracciando. Non può essere nello stesso componente che renderizza il tag `<form>` stesso, perché ha bisogno di accedere al contesto del modulo. Questo è il motivo per cui vedrai quasi sempre componenti come un `<SubmitButton />` creato separatamente per ospitare la logica `useFormStatus`.

Un semplice esempio: il pulsante di invio intelligente

Vediamo il caso d'uso più comune in azione. Invece di un `<button>` standard, creeremo un componente che è consapevole dello stato di invio del modulo.

File: SubmitButton.js

import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton() { const { pending } = useFormStatus(); return ( {pending ? 'Invio in corso...' : 'Iscriviti'} ); }

File: SignUpForm.js

import { SubmitButton } from './SubmitButton'; import { signUpAction } from './actions'; // A server action export function SignUpForm() { return ( Email:
); }

In questo esempio, il `SubmitButton` è completamente autonomo. Non riceve alcuna prop. Utilizza `useFormStatus` per sapere quando il `SignUpForm` è in sospeso e si disabilita automaticamente e cambia il suo testo. Questo è un modello potente per il disaccoppiamento e la creazione di componenti riutilizzabili e consapevoli del modulo.

Il cuore della questione: logica di validazione basata sullo stato

Ora arriviamo al concetto fondamentale. `useFormStatus` non è solo per gli stati di caricamento; è un abilitatore chiave di un modo diverso di pensare alla convalida.

Definizione di "Validazione dello stato"

La Validazione basata sullo stato è un modello in cui il feedback di convalida viene principalmente fornito all'utente in risposta a un tentativo di invio del modulo. Invece di convalidare ad ogni pressione di tasto (`onChange`) o quando un utente lascia un campo (`onBlur`), la logica di convalida primaria viene eseguita quando l'utente invia il modulo. Il risultato di questo invio, il suo *stato* (ad esempio, successo, errore di convalida, errore del server), viene quindi utilizzato per aggiornare l'interfaccia utente.

Questo approccio si allinea perfettamente con le Azioni del server React. L'azione del server diventa l'unica fonte di verità per la convalida. Riceve i dati del modulo, li convalida rispetto alle tue regole di business (ad esempio, "questa email è già in uso?") e restituisce un oggetto di stato strutturato che indica il risultato.

Il ruolo del suo partner: `experimental_useFormState`

`useFormStatus` ci dice *cosa* sta succedendo (in sospeso), ma non ci dice il *risultato* di ciò che è successo. Per questo, abbiamo bisogno del suo hook gemello: `experimental_useFormState`.

`useFormState` è un hook progettato per aggiornare lo stato in base al risultato di un'azione del modulo. Prende la funzione di azione e uno stato iniziale come argomenti e restituisce un nuovo stato e una funzione di azione avvolta da passare al tuo modulo.

const [state, formAction] = useFormState(myAction, initialState);

• `state`: conterrà il valore di ritorno dall'ultima esecuzione di `myAction`. È qui che otterremo i nostri messaggi di errore.
• `formAction`: questa è una nuova versione della tua azione che dovresti passare alla prop `action` del `<form>`. Quando viene chiamato, attiverà l'azione originale e aggiornerà lo `state`.

Il flusso di lavoro combinato: dal clic al feedback

Ecco come `useFormState` e `useFormStatus` lavorano insieme per creare un ciclo di convalida completo:

1. Renderizzazione iniziale: il modulo viene renderizzato con uno stato iniziale fornito da `useFormState`. Non vengono mostrati errori.
2. Invio dell'utente: l'utente fa clic sul pulsante di invio.
3. Stato in sospeso: l'hook `useFormStatus` nel pulsante di invio segnala immediatamente `pending: true`. Il pulsante viene disabilitato e mostra un messaggio di caricamento.
4. Esecuzione dell'azione: l'azione del server (avvolta da `useFormState`) viene eseguita con i dati del modulo. Esegue la convalida.
5. L'azione restituisce: l'azione non riesce nella convalida e restituisce un oggetto di stato, ad esempio:
   `{ message: "Validation failed", errors: { email: "This email is already taken." } }`
6. Aggiornamento dello stato: `useFormState` riceve questo valore di ritorno e aggiorna la sua variabile `state`. Questo attiva una ri-renderizzazione del componente del modulo.
7. Feedback dell'interfaccia utente: il modulo viene ri-renderizzato. Lo stato `pending` da `useFormStatus` diventa `false`. Il componente può ora leggere `state.errors.email` e visualizzare il messaggio di errore accanto al campo di input dell'email.

L'intero flusso fornisce un feedback chiaro e autorevole del server all'utente, guidato interamente dallo stato di invio e dal risultato.

Masterclass pratica: creazione di un modulo di registrazione multi-campo

Consolidiamo questi concetti costruendo un modulo di registrazione completo, in stile produzione. Useremo un'azione del server per la convalida e sia `useFormState` che `useFormStatus` per creare un'ottima esperienza utente.

Passaggio 1: definizione dell'azione del server con la convalida

Innanzitutto, abbiamo bisogno della nostra azione del server. Per una convalida robusta, utilizzeremo la popolare libreria Zod. Questa azione risiederà in un file separato, contrassegnato con la direttiva `'use server';` se stai utilizzando un framework come Next.js.

File: actions/authActions.js

'use server'; import { z } from 'zod'; // Define the validation schema const registerSchema = z.object({ username: z.string().min(3, 'Username must be at least 3 characters long.'), email: z.string().email('Please enter a valid email address.'), password: z.string().min(8, 'Password must be at least 8 characters long.'), }); // Define the initial state for our form export const initialState = { message: '', errors: {}, }; export async function registerUser(prevState, formData) { // 1. Validate the form data const validatedFields = registerSchema.safeParse( Object.fromEntries(formData.entries()) ); // 2. If validation fails, return the errors if (!validatedFields.success) { return { message: 'Validation failed. Please check the fields.', errors: validatedFields.error.flatten().fieldErrors, }; } // 3. (Simulate) Check if user already exists in the database // In a real app, you would query your database here. if (validatedFields.data.email === 'user@example.com') { return { message: 'Registration failed.', errors: { email: ['This email is already registered.'] }, }; } // 4. (Simulate) Create the user console.log('Creating user:', validatedFields.data); // 5. Return a success state // In a real app, you might redirect here using `redirect()` from 'next/navigation' return { message: 'User registered successfully!', errors: {}, }; }

Questa azione del server è il cervello del nostro modulo. È autonoma, sicura e fornisce una struttura di dati chiara sia per gli stati di successo che per quelli di errore.

Passaggio 2: creazione di componenti riutilizzabili e consapevoli dello stato

Per mantenere pulito il nostro componente del modulo principale, creeremo componenti dedicati per i nostri input e il pulsante di invio.

File: components/SubmitButton.js

'use client'; import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton({ label }) { const { pending } = useFormStatus(); return ( {pending ? 'Processing...' : label} ); }

Nota l'uso di `aria-disabled={pending}`. Questa è un'importante pratica di accessibilità, che garantisce che gli screen reader annuncino correttamente lo stato disabilitato.

Passaggio 3: assemblaggio del modulo principale con `useFormState`

Ora, uniamo tutto nel nostro componente del modulo principale. Useremo `useFormState` per connettere la nostra interfaccia utente all'azione `registerUser`.

File: components/RegistrationForm.js

'use client'; import { experimental_useFormState as useFormState } from 'react-dom'; import { registerUser, initialState } from '../actions/authActions'; import { SubmitButton } from './SubmitButton'; export function RegistrationForm() { const [state, formAction] = useFormState(registerUser, initialState); return (

Register

{state?.message && !state.errors &&

{state.message}

} {state?.message && state.errors &&

{state.message}

}

Username {state?.errors?.username && (

{state.errors.username[0]}

)}

Email {state?.errors?.email && (

{state.errors.email[0]}

)}

Password {state?.errors?.password && (

{state.errors.password[0]}

)}

); }

Questo componente è ora dichiarativo e pulito. Non gestisce alcuno stato da solo, a parte l'oggetto `state` fornito da `useFormState`. Il suo unico compito è renderizzare l'interfaccia utente in base a quello stato. La logica per disabilitare il pulsante è incapsulata in `SubmitButton`, e tutta la logica di convalida risiede in `authActions.js`. Questa separazione delle preoccupazioni è un enorme vantaggio per la manutenibilità.

Tecniche avanzate e best practice professionali

Sebbene il modello di base sia potente, le applicazioni del mondo reale richiedono spesso più sfumature. Esploriamo alcune tecniche avanzate.

L'approccio ibrido: unione della convalida istantanea e post-invio

La convalida basata sullo stato è eccellente per i controlli lato server, ma aspettare un roundtrip di rete per dire a un utente che la sua email non è valida può essere lento. Un approccio ibrido è spesso il migliore:

• Utilizza la convalida HTML5: Non dimenticare le basi! Attributi come `required`, `type="email"`, `minLength` e `pattern` forniscono un feedback istantaneo e nativo del browser a costo zero.
• Convalida lato client leggera: Per controlli puramente cosmetici o di formattazione (ad esempio, indicatore di forza della password), puoi comunque utilizzare una quantità minima di gestori `useState` e `onChange`.
• Autorità lato server: Riserva l'azione del server per la convalida più critica e di logica di business che non può essere eseguita sul client (ad esempio, controllo di nomi utente univoci, convalida rispetto ai record del database).

Questo ti offre il meglio di entrambi i mondi: feedback immediato per errori semplici e convalida autorevole per regole complesse.

Accessibilità (A11y): creazione di moduli per tutti

L'accessibilità non è negoziabile. Quando implementi la convalida basata sullo stato, tieni a mente questi punti:

• Annuncia gli errori: Nel nostro esempio, abbiamo utilizzato `aria-live="polite"` sui contenitori dei messaggi di errore. Questo dice agli screen reader di annunciare il messaggio di errore non appena appare, senza interrompere il flusso corrente dell'utente.
• Associa gli errori agli input: Per una connessione più robusta, utilizza l'attributo `aria-describedby`. L'input può puntare all'ID del suo contenitore di messaggi di errore, creando un collegamento programmatico.
• Gestione del focus: Dopo un invio con errori, valuta la possibilità di spostare programmaticamente il focus sul primo campo non valido. Questo evita agli utenti di dover cercare cosa è andato storto.

UI ottimistica con la proprietà `data` di `useFormStatus`

Immagina un'app di social media in cui un utente pubblica un commento. Invece di mostrare uno spinner per un secondo, puoi far sentire l'app istantanea. La proprietà `data` di `useFormStatus` è perfetta per questo.

Quando il modulo viene inviato, `pending` diventa true e `data` viene popolato con il `FormData` dell'invio. Puoi immediatamente renderizzare il nuovo commento in uno stato visivo temporaneo, 'in sospeso', usando questi `data`. Se l'azione del server ha successo, sostituisci il commento in sospeso con i dati finali dal server. Se fallisce, puoi rimuovere il commento in sospeso e mostrare un errore. Questo rende l'applicazione incredibilmente reattiva.

Navigare nelle acque "sperimentali"

È fondamentale affrontare il prefisso "sperimentale" in `experimental_useFormStatus` e `experimental_useFormState`.

Cosa significa realmente "Sperimentale"

Quando React etichetta un'API come sperimentale, significa:

• L'API potrebbe cambiare: Il nome, gli argomenti o i valori di ritorno potrebbero essere alterati in una futura release di React senza seguire il versionamento semantico standard (SemVer) per le modifiche che causano interruzioni.
• Potrebbero esserci bug: Essendo una nuova funzionalità, potrebbe avere casi limite che non sono ancora pienamente compresi o risolti.
• La documentazione potrebbe essere scarsa: Sebbene i concetti fondamentali siano documentati, guide dettagliate sui modelli avanzati potrebbero essere ancora in evoluzione.

Quando adottare e quando aspettare

Quindi, dovresti usarlo nel tuo progetto? La risposta dipende dal tuo contesto:

• Buono per: Progetti personali, strumenti interni, startup o team a proprio agio con la gestione di potenziali modifiche API. Utilizzarlo all'interno di un framework come Next.js (che ha integrato queste funzionalità nel suo App Router) è generalmente una scommessa più sicura, poiché il framework può aiutare ad astrarre parte del churn.
• Utilizzare con cautela per: Applicazioni aziendali su larga scala, sistemi mission-critical o progetti con contratti di manutenzione a lungo termine in cui la stabilità dell'API è fondamentale. In questi casi, potrebbe essere prudente aspettare fino a quando gli hook non vengono promossi a un'API stabile.

Tieni sempre d'occhio il blog e la documentazione ufficiali di React per gli annunci relativi alla stabilizzazione di questi hook.

Conclusione: il futuro dei moduli in React

L'introduzione di `experimental_useFormStatus` e delle sue API correlate è più di un semplice nuovo strumento; rappresenta un cambiamento filosofico nel modo in cui creiamo esperienze interattive con React. Abbracciando le fondamenta della piattaforma web e co-localizzando la logica stateful sul server, possiamo creare applicazioni più semplici, più resilienti e spesso più performanti.

Abbiamo visto come `useFormStatus` fornisce un modo pulito e disaccoppiato per i componenti di reagire al ciclo di vita di un invio del modulo. Elimina il prop drilling per gli stati in sospeso e abilita componenti UI eleganti e autonomi come uno `SubmitButton` intelligente. Se combinato con `useFormState`, sblocca il potente modello di convalida basata sullo stato, in cui il server è l'autorità ultima e la responsabilità principale del client è quella di renderizzare lo stato restituito dall'azione del server.

Mentre il tag "sperimentale" giustifica un certo grado di cautela, la direzione è chiara. Il futuro dei moduli in React è uno di miglioramento progressivo, gestione dello stato semplificata e una potente e fluida integrazione tra la logica client e server. Padroneggiando questi nuovi hook oggi, non stai solo imparando una nuova API; ti stai preparando per la prossima generazione di sviluppo di applicazioni web con React.